26.5.1 Comment Commands

The following commands operate on comments:

M-;

Insert or realign comment on current line; if the region is active, comment or uncomment the region instead (comment-dwim).

C-x C-;

Comment or uncomment the current line (comment-line).

C-u M-;

Kill comment on current line (comment-kill).

C-x ;

Set comment column (comment-set-column).

C-M-j

M-j

Like RET followed by inserting and aligning a comment (comment-indent-new-line). See Multi-Line Comments.

M-x comment-region

C-c C-c (in C-like modes)

Add comment delimiters to all the lines in the region.

The command to create or align a comment is M-; (comment-dwim). The word “dwim” is an acronym for “Do What I Mean”; it indicates that this command can be used for many different jobs relating to comments, depending on the situation where you use it.

When a region is active (see Mark), M-; either adds comment delimiters to the region, or removes them. If every line in the region is already a comment, it uncomments each of those lines by removing their comment delimiters. Otherwise, it adds comment delimiters to enclose the text in the region.

If you supply a prefix argument to M-; when a region is active, that specifies the number of comment delimiters to add or delete. A positive argument n adds n delimiters, while a negative argument -n removes n delimiters.

If the region is not active, and there is no existing comment on the current line, M-; adds a new comment to the current line. If the line is blank (i.e., empty or containing only whitespace characters), the comment is indented to the same position where TAB would indent to (see Basic Indent). If the line is non-blank, the comment is placed after the last non-whitespace character on the line; normally, Emacs tries putting it at the column specified by the variable comment-column (see Options for Comments), but if the line already extends past that column, it puts the comment at some suitable position, usually separated from the non-comment text by at least one space. In each case, Emacs places point after the comment’s starting delimiter, so that you can start typing the comment text right away.

You can also use M-; to align an existing comment. If a line already contains the comment-start string, M-; realigns it to the conventional alignment and moves point after the comment’s starting delimiter. As an exception, comments starting in column 0 are not moved. Even when an existing comment is properly aligned, M-; is still useful for moving directly to the start of the comment text.

C-x C-; (comment-line) comments or uncomments complete lines. When a region is active (see Mark), C-x C-; either comments or uncomments the lines in the region. If the region is not active, this command comments or uncomments the line point is on. With a positive prefix argument n, it operates on n lines starting with the current one; with a negative n, it affects n preceding lines. After invoking this command with a negative argument, successive invocations with a positive argument will operate on preceding lines as if the argument were negated.

C-u M-; (comment-dwim with a prefix argument) kills any comment on the current line, along with the whitespace before it. Since the comment is saved to the kill ring, you can reinsert it on another line by moving to the end of that line, doing C-y, and then M-; to realign the comment. You can achieve the same effect as C-u M-; by typing M-x comment-kill (comment-dwim actually calls comment-kill as a subroutine when it is given a prefix argument).

The command M-x comment-region is equivalent to calling M-; on an active region, except that it always acts on the region, even if the mark is inactive. In C mode and related modes, this command is bound to C-c C-c. The command M-x uncomment-region uncomments each line in the region; a numeric prefix argument specifies the number of comment delimiters to remove (negative arguments specify the number of comment to delimiters to add).

For C-like modes, you can configure the exact effect of M-; by setting the variables c-indent-comment-alist and c-indent-comments-syntactically-p. For example, on a line ending in a closing brace, M-; puts the comment one space after the brace rather than at comment-column. For full details see Comment Commands in The CC Mode Manual.